Ansible2.4 から Ansible 2.5
Python で実装された構成管理ツール Ansibleについて、
各バージョンでの違いをまとめた "Ansible Migration Guide" を翻訳しています。
プレイブック
動的インクルードと属性継承
Aniable 2.4では、動的インクルード(include_tasks)と静的インポート(import_tasks)の概念が導入され、
動的インクルードと静的インクルードの間のインクルードの動作の違いが明確に定義されました。
動的include_ *に適用されるすべての属性はインクルード自体にのみ適用され、静的import_ *に適用される属性はその中のタスクによって継承されます。
この分離は、Ansible 2.4 で部分的にしか実装されていませんでした。
Ansible 2.5以降、この作業は完了し分離は設計通りに動作するようになり、 include_ * タスクに適用される属性は、その中のタスクに継承されません。
Ansible 2.5 以前で動作していた同じ挙動をさせるためには、プレイブックでは必要なタスクに属性を明示的に適用するか、ブロックを使用して属性を多くのタスクに適用する必要があります。 もう一つの選択肢は、ダイナミックタスクではなく、静的import_ * を可能な限り使用することです。
Ansible 2.4以前でのタスクとインクルードファイルの記述
code: ansibkle
- include_tasks: "{{ ansible_distribution }}.yml"
tags:
- distro_include
インクルードファイル
code: ansile
- block:
- debug:
msg: "In included file"
- apt:
name: nginx
state: latest
Ansible 2.5 からのタスクとインクルードファイルの記述
code: ansible
- include_tasks: "{{ ansible_distribution }}.yml"
tags:
- distro_include
インクルードファイル
code: ansible
- block:
- debug:
msg: "In included file"
- apt:
name: nginx
state: latest
tags:
- distro_include
この例でもわかるように、Ansible 2.5のインクルードファイルで distro_include というタグが再度定義されています。
タグは自動的に継承されません。
キーワードとインライン変数の処理が修正されました
キーワードとインライン変数の扱いについて、くつかの修正を加えられました。
残念ながら、これらの変更で、ロールを呼び出すときに name がキーワードか変数かを指定することが必要になりました。
あなたが次のようなプレイブックを持っているとすると、
code: ansible
roles:
- { role: myrole, name: Justin, othervar: othervalue, become: True}
Ansiuble は定義にある name をキーワードとして判断して動作するためエラーになりました。
Ansisble 2.5 からは、キーワードでもある name を変数として使いたいときは、name を変数として明示的に宣言する必要があります。
code: ansible
roles:
- { role: myrole, vars: {name: Justin, othervar: othervalue}, become: True}
with_X からループへの移行
Ansible 2.5では、with_X スタイルループの代わりに、新しいloop キーワードを使用するように推奨されています。
多くの場合、loop構文は、query やlookup といったより複雑で使い方ではなく、フィルタを使用して表現する方が効果的です。
次の例では、多くの一般的な with_X スタイルループをループとフィルタに変換する方法を示します。
with_list
with_list はそのままloop に置き換えることができます。
code: ansible
- name: with_list
debug:
msg: "{{ item }}"
with_list:
- one
- two
- name: with_list -> loop
debug:
msg: "{{ item }}"
loop:
- one
- two
with_items
with_items は loop と filter を使って置き換えることができます。
code: ansible
- name: with_items
debug:
msg: "{{ item }}"
with_items: "{{ items }}"
- name: with_items -> loop
debug:
msg: "{{ item }}"
loop: "{{ items|flatten(levels=1) }}"
with_indexed_items
with_indexed_items は loop と flatten フィルタおよび loop_control.index_var を使って置き換えることができます。
code: ansible
- name: with_indexed_items
debug:
msg: "{{ item.0 }} - {{ item.1 }}"
with_indexed_items: "{{ items }}"
- name: with_indexed_items -> loop
debug:
msg: "{{ index }} - {{ item }}"
loop: "{{ items|flatten(levels=1) }}"
loop_control:
index_var: index
with_flattened
with_flattened は loop と flatten フィルタで置き換えることができます。
code: ansible
- name: with_flattened
debug:
msg: "{{ item }}"
with_flattened: "{{ items }}"
- name: with_flattened -> loop
debug:
msg: "{{ item }}"
loop: "{{ items|flatten }}"
with_together
with_together は loop と zjpフィルタを使って置き換えることができます。
code: ansible
- name: with_together
debug:
msg: "{{ item.0 }} - {{ item.1 }}"
with_together:
- "{{ list_one }}"
- "{{ list_two }}"
- name: with_together -> loop
debug:
msg: "{{ item.0 }} - {{ item.1 }}"
loop: "{{ list_one|zip(list_two)|list }}"
with_dict
with_dict は dictsort と dict2items いずれかのフィルタと loop を使って置き換えることができます。
code: ansible
- name: with_dict
debug:
msg: "{{ item.key }} - {{ item.value }}"
with_dict: "{{ dictionary }}"
- name: with_dict -> loop (option 1)
debug:
msg: "{{ item.key }} - {{ item.value }}"
loop: "{{ dictionary|dict2items }}"
- name: with_dict -> loop (option 2)
debug:
msg: "{{ item.0 }} - {{ item.1 }}"
loop: "{{ dictionary|dictsort }}"
with_sequence
with_sequence loop と range 関数、場合によっては format フィルタを使って置き換えることができます。
code: ansible
- name: with_sequence
debug:
msg: "{{ item }}"
with_sequence: start=0 end=4 stride=2 format=testuser%02x
- name: with_sequence -> loop
debug:
msg: "{{ 'testuser%02x' | format(item) }}"
# range is exclusive of the end point
loop: "{{ range(0, 4 + 1, 2)|list }}"
with_subelements
with_subelements は loop と subelements フィルタを使って置き換えることができます。
code: ansible
- name: with_subelements
debug:
msg: "{{ item.0.name }} - {{ item.1 }}"
with_subelements:
- "{{ users }}"
- mysql.hosts
- name: with_subelements -> loop
debug:
msg: "{{ item.0.name }} - {{ item.1 }}"
loop: "{{ users|subelements('mysql.hosts') }}"
with_nested / with_cartesian
with_nested と with_cartesian は loop と product フィルタを使って置き換えることができます。
code: ansible
- name: with_nested
debug:
msg: "{{ item.0 }} - {{ item.1 }}"
with_nested:
- "{{ list_one }}"
- "{{ list_two }}"
- name: with_nested -> loop
debug:
msg: "{{ item.0 }} - {{ item.1 }}"
loop: "{{ list_one|product(list_two)|list }}"
with_random_choice
with_random_choice は loop は不要で random フィルタで置き換えることができます。
code: ansible
- name: with_random_choice
debug:
msg: "{{ item }}"
with_random_choice: "{{ my_list }}"
- name: with_random_choice -> loop (No loop is needed here)
debug:
msg: "{{ my_list|random }}"
tags: random
廃止予定
フィルタとして使用されるJinja テスト
Ansible が提供している Jina のテストフィルタは、Ansible 2.9で削除されます。
Ansible 2.5以前は、Anipalに含まれている Jinja テストフィルタが最も頻繁に使用されていました。
variable | filter_name のように参照しているとき、Jinja テストは variable をテスト名として参照するようになります。
Jinja テストは比較に使用されていて、フィルタはデータ操作に使用されたり、Jinja で記述されたアプリケーションとは異なる使いかたがされていました。
この変更は、Jinjaの理解を深め、それぞれ適切に使用できるようにコンセプトを区別するのに役立ちます。
Anipal 2.5以降では、Anipal提供のjinjaテストでフィルタ構文を使用すると、非推奨エラーが表示されます。
Ansible 2.4 以前で次のように記述されていたコードは
code: ansible
when:
- result | failed
- not result | success
Ansible 2.5 では次のように変更することになります。
code: ansible
when:
- result is failed
- results is not successful
廃止警告に加えて、古いテストのエイリアスである多くの新しいテストが導入されました。 これらの新しいテストは、successのエイリアスとなる新しい successful などのように、Jinjaのテスト構文をより自然な言葉となるようにします。
code: ansible
when: result is successful
さらに、フィルタ構文を使用して適切なジンジャーテスト構文に変換するためのスクリプトが作成されました。 このスクリプトは、すべてのAnatile統合テストを正しい形式に変換するために使用されています。 いくつかの制限事項が文書化されており、修正されたプレイブックを実行する前に、このスクリプトが行ったすべての変更を正確に評価する必要があります。
Ansible の fact の名前空間
Ansible の fact は、歴史的にansible_* のような名前でfact名前空間に置かれています。
新しい名前空間は ansible_facts.* として置かれます。
例えば、anecess_distribution は変数構造 ansible_facts.distribution として照会されます。
新しい構成変数 inject_facts_as_vars が、supported.cfg に追加されました。 デフォルト設定の True は、
古い ansible_ * の場所に設定されているfacts変数の Ansible 2.4での動作を保持しています(新しい名前空間にも書き込んでいます)。
この変数は、将来のリリースでは False に設定されます。
inject_facts_as_vars が False に設定されている場合、新しい ansible_facts.* 名前空間を通じて参照する必要があります。
モジュール
よく利用されているモジュールについて以下に説明します。
github_release
Ansible 2.4 以前では、create_release のステータスを使用してGitHubリリースを作成した後、github_releaseモジュールは状態が変更されたことを報告はしていませんでした。
Aniableバージョン2.5以降では、create_release のステータスを使用してGitHubリリースを作成した後、github_releaseモジュールは状態が変更されたことを報告するようになりました。
削除されたのモジュール
次のモジュールはもう存在していません。
nxos_mtu : nxos_system の system_mtu オプション や nxos_interface を使用すること
cl_interface_policy : nclu を使用すること
cl_bridge: nclu を使用すること
cl_img_install: nclu を使用すること
cl_ports : nclu を使用すること
cl_license : nclu を使用すること
cl_interface : nclu を使用すること
cl_bond : nclu を使用すること
ec2_vpc : ec2_vpc_net とサポートモジュール ec2_vpc_igw、 ec2_vpc_route_table、 ec2_vpc_subnet、 ec2_vpc_dhcp_option、ec2_vpc_nat_gateway、 ec2_vpc_nacl を使用するこよ
ec2_ami_search: ec2_ami_facts を使用するこよ
docker : docker_container と docker_image を使用すること
非推奨モジュール
以下のモジュールは、Ansible 2.9で削除されます。 あなたのプレイブックを修正してください。
nxos_ip_interface : nxos_l3_interface を使用すること
nxos_portchannel : nxos_linkagg を使用すること
nxos_switchport : nxos_l2_interface を使用すること
panos_security_policy: panos_security_rule を使用すること
panos_nat_policy: panos_nat_rule を使用すること
vsphere_guest: vmware_guest を使用すること
注目すべきモジュールの変更
stat と win_stat モジュールは、オプション get_md5 のデフォルトを true から false に変更しました。
このオプションは、Aniable 2.9から削除されます。 MD5チェックサムが必要な場合は、get_checksum:True とchecksum_algorithm:md5 オプションが引き続き使用できます。
osx_say モジュールは名前が sayに 変更になりました。
symlinkを扱うことができるいくつかのモジュールでは、follow オプションのデフォルト値が、以下の動作を標準化する機能の一部として変更されました。
fileモジュールは follow = False から follow = True に変更されました。その目的はファイルの属性を変更することで、ほとんどのシステムでは属性はシンボリックリンクに適用されず、実際のファイルにのみ適用されます。
replaceモジュールは、既存のファイルの内容を変更するので、そのfollowパラメータが削除されているので、リンク自体で動作することは意味がありません。
blockinfileモジュールは、既存のファイルの内容を変更するので、その followパラメータが削除されているので、リンク自体を操作する意味がありません。
Ansible 2.5.3では、templateモジュールは src ファイルが適切なutf-8であることがより厳密になりました。 以前は、templateモジュールのsrcファイルのutf8以外で設定しても出力ファイルを変更しました(非utf8文字はUnicode置換文字に置き換えられます)。 Python2では、モジュールは "Template source files is utf-8 encoded"というメッセージでエラーになります。 Python3では、モジュールはまずutf8以外の文字を逐語的に渡して、それが成功しなければ失敗します。
プラグイン
開発者は、新しいプラグイン設定システムをサポートするプラグインタイプの設定オプションに''doc fragments''を使用できるようになりました。
インベントリ
インベントリプラグインは微調整されており、いくつかの共通機能を追加されました。
処理の重い API / DBクエリを避けるためにキャッシュプラグインを使用する機能は、デフォルトでは無効になっています。 インベントリスクリプトを使用している場合は、すでにキャッシュをサポートしているものもあれば、Ansible の知識と管理の範囲外のものもあります。 内部キャッシュに移動すると、Ansible の既存のキャッシュの更新/無効化メカニズムを使用できます。
プラグインが 一般的なYAML設定フォーマット を使用している場合、正しいプラグインが自動的に検出される新しい 'auto'プラグインが導入さています。以前の host_list、script、yaml、iniプラグインは引き続き動作しますが、auto プラグインは最後に使用しようとしています。 有効なプラグインをカスタマイズした場合は、新しいautoプラグインを組み込むように設定を修正する必要があります。
Shell
shellプラグインは、新しいプラグイン構成フレームワークに移行されました。 より多くの設定をカスタマイズすることが可能になりました。また、以前は「グローバル」だった設定も、ホスト固有の変数を使用して上書きすることができます。
たとえば、system_temps は新しい設定で、Ansibleが「システム一時ディレクトリ」とみなすものを制御することができます。 これは、管理者以外のユーザーの権限をエスカレートするときに使用されます。 以前はこれが '/ tmp'にハードコードされていましたが、システムによっては権限の昇格に使用できませんでした。 この設定のデフォルトは['/ var / tmp'、 '/ tmp']になります。
もう1つの新しい設定はadmin_usersです。この設定では、「管理者」とみなされるユーザーのリストを指定できます。 以前はこれが root にハードコードされていました。 これはデフォルトで[root、toor、admin]になります。 この情報は、remote_tempディレクトリとsystem_tempsディレクトリのどちらかを選択するときに使用されます。
完全なリストについては、使用しているシェルプラグインを確認してください。デフォルトのシェルプラグインはshです。
グローバル構成の制限を回避する必要があったものは、ホスト/グループ単位の設定に移行できるようになりましたが、前提条件が環境に依存しない場合、新しいデフォルトが既存コードの使用と競合する可能性があります。
フィルタ
プラグインから反復可能でない値が返された場合、lookupプラグインAPIはエラーを送出するように変更されています。 以前は、エラーや警告なしに、プラグインによって返された数値やその他の反復可能な型は受け入れられませんでした。 この変更は、プラグインが常にリストを返さなければならないために行われました。 文字列やその他の反復可能な値を返すプラグインはエラーを送出しませんが、予期しない動作を引き起こす可能性があります。 リストを返さないカスタムルックアッププラグインを使用している場合は、リスト内の戻り値をラップするように変更する必要があります。
Lookup
lookup によって引き起こされるエラーをどう処理するかを制御するための、新しいオプションがlookupプラグインに追加されました。
このオプションの有効な値は warn、ignore、およびstrictです。
ネットワーク
トップレベルの接続引数は Ansible 2.9 で削除されます
username、host、password などのトップレベルの接続引数は廃止され、バージョン2.9では削除されます。
Ansible 2.4 以前のコード
code: ansible
- name: example of using top-level options for connection properties
ios_command:
commands: show version
host: "{{ inventory_hostname }}"
username: cisco
password: cisco
authorize: yes
auth_pass: cisco
これを Ansible 2.5 で実行すると次のように警告表示がされます。
code: output
DEPRECATION WARNING: Param 'username' is deprecated. See the module docs for more information. This feature will be removed in version 2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.
DEPRECATION WARNING: Param 'password' is deprecated. See the module docs for more information. This feature will be removed in version 2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.
DEPRECATION WARNING: Param 'host' is deprecated. See the module docs for more information. This feature will be removed in version 2.9. Deprecation warnings can be disabled by setting deprecation_warnings=False in ansible.cfg.
新しい接続タイプ network_cli と netconf(下記参照)を使って、標準の接続可能な接続プロパティをグループ単位でインベントリに設定することが推奨されています。 プレイブックとインベントリファイルを更新すると、become(それをサポートするプラットフォームで)に変更することが簡単にできます。
Ansible 2.4 以前
code: ansible
---
vars:
cli:
host: "{{ inventory_hostname }}"
username: operator
password: secret
transport: cli
tasks:
- nxos_config:
src: config.j2
provider: "{{ cli }}"
username: admin
password: admin
Ansible 2.5 以降
code: inventory
ansible_connection=network_cli
ansible_network_os=nxos
ansible_user=operator
ansible_password=secret
code: ansible
tasks:
- nxos_config:
src: config.j2
開発者向け:共有モジュールユーティリティーが移動されています
Ansible 2.5から、networkモジュール用の共有モジュールユーティリティが、.module_utils.network に移動されました。
プラットフォームに依存しないユーティリティは、anonymous.module_utils.network.common にあります。
プラットフォーム固有のユーティリティは、anonymous.module_utils.network.{{platform}} にあります。
モジュールが共有モジュールユーティリティを使用する場合は、すべての参照を更新する必要があります。
たとえば、次のように変更します。
Ansible 2.4 以前
code: python
from ansible.module_utils.vyos import get_config, load_config
Ansible 2.5 以降
code: python
from ansible.module_utils.network.vyos.vyos import get_config, load_config